\documentclass{sig-alt-release2}
\usepackage{url}
\usepackage{color}
\usepackage{graphics,graphicx}

\usepackage{epsfig}
\usepackage{epstopdf}

\usepackage{colortbl}
\usepackage{multirow}
\usepackage{booktabs}
\usepackage{ifthen}  
\usepackage{appendix}

\begin{document}
\newcommand{\todo}[1]{\textcolor{red}{#1}}
\def\newblock{\hskip .11em plus .33em minus .07em}

\conferenceinfo{DIM3} {2010, Glasgow, UK} 
\CopyrightYear{2010}
\clubpenalty=10000
\widowpenalty = 10000

\title{{DIM3 Implementation Report}}

\numberofauthors{5}
\author{
\alignauthor
Haroon Ahmed \\
Steven Callander \\
Martin Foley \\
Aidan Jack \\
Ilze Poca  \\
	   \affaddr{Group A}\\
      \affaddr{DIM3}\\
}
\maketitle

\begin{abstract}
This is a design report for a web-based chess game, that provides a simple interface for casual players to play against the computer. This product uses an existing chess engine together with a custom made middle-ware acting as a server. This report also describes all the interactions and messages sent between the client and server, conclusions about the project and future work section.



\end{abstract}

\section{Aim of Application}
The application is a web-based chess game, allowing users to play against a chess engine on a remote server. The purpose of this application is to provide a fun web-based chess game for casual players. \\
There are several assumptions about potential users of this application. One assumption is that potential users would have a basic understanding of chess, including legal moves and other rules. Users also need access to a computer with an Internet connection and a web browser.\\
The main goal of the system is to provide a simple and user friendly design that would encourage novice users to play the game and possibly improve their game play skills.\\
It was planned to initially implement the program as player playing against the chess engine, hosted on the server. Then if feasible, player versus player functionality would be added to allow a user to play against another user on a different computer. The final goal was to provide functionality to log in a server and store game statistics about each user's games.\\
The project used an already existing chess engine written in Java and the goal was to adapt it for use on web.\\
A formal list of requirements written using a MoSCoW technique is provided below.\\
{\bf Must-have requirements:}
\begin{itemize}
\item Functionality to allow a human user to play against an AI opponent;
\item Select a move and communicate it to the user in a timely fashion (non-functional);
\item Show which player's turn it is (functional);
\item Decide if a chosen move is valid (functional);
\item Stop a human player from making an illegal move (functional);
\item Display a move made by the computer (functional);
\item Show the current state of the board (functional);
\item Be able to accept a move from the user (functional)
\end{itemize}
{\bf Should-have requirements:}
\begin{itemize}
\item Variable level of difficulty (functional);
\item Make all previous moves visible to the player (functional);
\end{itemize}
{\bf Could-have requirements:}
\begin{itemize}
\item Have user accounts and store statistics on games in a separate database (functional);
\item Use a security system for the user accounts, statistics database and chess engine (non-functional)
\end{itemize}
{\bf Would be nice to have requirements:}
\begin{itemize}
\item Player versus player functionality (functional);
\item Communication between players via text chat (functional);
\item Profanity filter on text chat (non-functional)
\end{itemize}

The scope of the application was appropriate due to a large number of existing chess games on-line. The team therefore felt that there may be existing support and discussion for on-line chess games, which may aid our task.\\
The design goals, although very complicated and ambitious, were achievable as individual targets, however, it was unlikely that all requirements less than must-have priority would be met. \\
The application was rather complex due to the many different frameworks used for each component of the application and the different communication methods used between these components. \\
Distribution across the web was appropriate due to the high number of on-line games currently available. Chess is an exceedingly popular game so the team felt that there is a suitable audience for our chess web app.

\section{Application Architecture}
The application needs to store the current state of the board used in the chess game involving the user. This board is stored in the chess engine and passed to the browser through the middle-ware.\\
\begin{figure}[h]
  \caption{Architecture Diagram}
  \begin{center}
    \includegraphics[width=80mm]{diagram3.png} 
  \end{center}
\end{figure}
{\bf Information stored within the board includes:}
\begin{itemize}
\item The current location of all the pieces on the board;
\item Who's turn it is;
\item The current game difficulty level;
\item A list of the pieces captured during the course of the game;
\item Whether a castling or an en passant move is currently possible;
\item How many moves have been made in the current game;
\item Some important data for the evaluator (not relevant for the web app);
\item Whether or not the black or white king is in check
\end{itemize}
{\bf The back-end is provided by the existing chess engine. The services provided are:}
\begin{itemize}
\item Generates the opening game state;
\item Generates a list of legal moves from a chosen start square for the player's move;
\item Returns a board based on the current state of the board and a user move;
\item Calculates the best move from the computer's point of view and returns the resulting board to the client;
\item Determines if the game is over, and communicates this to the client
\end{itemize}
No functionality overlaps between any of the components in the application. All communication is done through specific channels using carefully chosen protocols to ensure data integrity. Content and presentation have been kept separate by an intermediate component (middle-ware) which ensures that neither communicates directly with the other. The application also utilizes information hiding through encapsulation in the form of separated components.\\
The team considered using Spring framework or Django. The Spring framework was considered because it uses Java just like the chess engine simplifying the communication between the two, however the team decided against Spring due to lack of familiarity with it's operation. Django is a framework that uses Python programming language and simplifies creating a new website. Although the team had never used Django we felt that it would be easier to find assistance and more feedback if this framework was used. \\
{\bf The advantages of using a Web Application Framework are:}
\begin{itemize}
\item Web application frameworks provide partial implementation of the project, so there will be less effort required from the team to write the code.
\item The framework provides a large proportion of the 'boilerplate' code, meaning that the main functionality can be implemented quickly.
\item Frameworks greatly increase development rate.
\end{itemize} 
{\bf The disadvantages of using a framework are:}
\begin{itemize}
\item Some components of the framework cannot be altered. This may lead to undesired functionality.
\item Frameworks are traditionally poorly documented. Effort may be required to become familiar with the framework, which may hinder development rate.
\item A framework may produce more code than is strictly necessary. This will lead to difficulty reading and understanding source code.
\end{itemize}
However despite all the advantages described above the team realised that Django framework is best used if there is a need for a database and since this application does not need one, in the end it was decided to use a custom made middle-ware for this system.\\




\section{Message Parsing}
In order to keep the state of the board consistent between the client and engine we must pass messages to the server any time the user performs an action that changes the state of the board. Our board is represented by a list of strings and the following is a list of scenarios and what we will pass to between the client and the engine in each case:
\begin{itemize}
\item
User starts the application \newline
A GET request for a new board is transmitted that tells the engine to start a new game and a new board should be sent to the client. A board is represented as an array of strings detailing where all the pieces are on the board.
\item
User clicks on a square/makes a move \newline
This transmits a string to the chess engine which will then return the new state of the board. If the move made is legal, the returned board will contain the user's move and also the the chess engine's response move. If the move is not legal, the board is returned in the state it was in before and the illegal user move is not displayed.
\item
The end of the game\newline
When a move is made that ends the game (by user or the engine), not only an update board is sent, but also a message displaying if it is a checkmate or stalemate. An appropriate message is then displayed in the browser for the user.\\

\end{itemize}
{\bf Communication with middle-ware}\newline
The middle-ware helps the browser to interact with the chess engine. The browser send a HTTP GET request to the middle-ware with the square clicked encoded in the message. The middle-ware parses out the square and checks if this is the first or the second click of the move. If it is the first, it stores the square and sends the same square twice to the chess engine, which interprets this as a special null move and returns the same board back to the middle-ware which then encodes it into a HTML page and returns it to the browser. \\
If the square clicked is the second square of the move, the middle-ware sends both the stored first square and the second square to the engine. The chess engine then recognises this as a normal move, checks if it is legal and if it is looks for a response move. When the response move is found, the chess engine returns an updated board with both moves to the middle-ware which in return encodes it into a HTML page and sends it to the browser.\\
The middle-ware consists of both a server and a client written in C. It acts as a server to the web browser and as a client to the chess engine. Both the server and the client used in the middle-ware was adapted from an assessed exercise for NS3. \\
Figure 3 (Appendix) details the interactions between all the components of the application.\\

\section{Client Interface}
% INSERT IMAGE

\begin{figure}[h]
  \caption{Wireframe}
  \begin{center}
    \includegraphics[width=80mm]{screenshot3.png} 
  \end{center}
\end{figure}


%\begin{center}
 %	\includegraphics[width=80mm]{screenshot3.png} 
 %%	\caption{Figure 1. Wireframe}
%\end{center}

% END IMAGE
When the user enters the website a new board is presented and a game is automatically started. The user can then begin playing the game by selecting pieces and making moves. When the game ends a message is displayed informing the user about a checkmate or a stalemate and how to start a new game.\\
To start a new game the user has to click the same square twice (not a double click).\\
The user interface is made as simple as possible to allow users to quickly start the game and enjoy playing it. An unobtrusive colour scheme was chosen for board to make the application more user friendly. A classic set of icons was used to represent the chess pieces.\\
Figure 2 shows the user interface of the system. The elements of the design are:
\begin{itemize}
\item 1 - The logo of the program;
\item 2 - The chess board
\end{itemize}

\section{Design Revision / Feedback}
{\bf Feedback from design report:}
\begin{itemize}
\item The architecture diagram was not clearly labelled;
\item There was no diagram of the data model;
\item Some diagrams are written on paper, causing readability problems;
\item Some requirements were written in an unclear manner;
\item The report was heavily listed, some appearance of flow would be better;
\item The report showed a lack of knowledge in some of the technologies used;
\item The design is not entirely suitable to a web application framework;
\item Discrepancies in the Message Parsing section
\end{itemize}
To address the feedback, we have rewritten certain sections of the report. Most notably the message parsing section. The diagrams have been recreated for clarity purposes. The report takes more of a paragraph structure than a list, as was suggested from some feedback. One reviewer said that a web application framework was not suitable for this project. During development, this was confirmed and the framework was dropped.\\
The feedback has allowed us to scale back our project scope. Without which, many man hours may have been spent in creating a product that potentially did not work. The feedback also pointed out some flaws in the project design and architecture, which may not have been noticed until much later in the development, when they could have caused much deeper issues. The flaws in the requirements allowed us to clarify what exactly the program needed to do, which meant that our separate development teams had a clearer picture than what they would have.

\section{Implementation Notes}

Due to the complexity of the application, we were unable to implement all the features that we envisaged originally. We did however manage to implement enough features for the user to be able to play a game of chess against the computer.\\
The following requirements were implemented in the final version:
\begin{itemize}

\item {\bf Must Have}
\begin{itemize}
\item Functionality to allow a human user to play against an AI opponent (functional);
\item Select a move and communicate it to the user in a timely fashion (non-functional);
\item Decide if a chosen move is valid (functional);
\item Stop a human player from making an illegal move (functional);
\item Display a move made by the computer (functional);
\item Show the current state of the board (functional);
\item Be able to accept a move from the user (functional)
\end{itemize}



\end{itemize}

The following features were originally designed however were not implemented:

\begin{itemize}




\item {\bf Must Have Requirements}

\begin{itemize}
\item {\bf Show whose turn it is (functional)}\\
This was not implemented because it was not relevant for our final product. This is because the board is returned with the computers response to the players move already made. Also as stated below there was no player vs player functionality for which turn indication would have been appropriate.
\end{itemize}

\item {\bf Should Have}

\begin{itemize}
\item {\bf Make all previous moves visible to the player (functional)}  \\
This is a requirement that we did not implement due to time constraints. It would have been very easy to implement with the design of our system and would be something easy to add for suture work (see Section \ref{futurework}).
\end{itemize}

\item {\bf Could-have requirements}

\begin{itemize}
\item {\bf Have user accounts and store statistics on games in a separate database (functional)} \\
We originally hoped that we could store information on users and their statistics over time. However because we focuses on fulfilling our priority requirements we decided not to use a data base or Django framework. In order to implement user accounts and stats a database would have been required.
\item {\bf Use a security system for the user accounts, statistics database and chess engine (Non-functional)}\\
This requirement is obsolete because as stated above we never used a database in our implementation.
\end{itemize}

\item {\bf Would be nice to have requirements}

\begin{itemize}
\item {\bf Player vs Player (functional)} \\
This would have been fairly trivial to implement provided both players were on the same computer, however due to time constraints this was not implemented (see Section \ref{futurework}).\\
In order to implement this for users playing across different computers this would have required we would have been required to make the board dynamically refresh and due to time constraints we could not research the technologies to accomplish this.

\item {\bf Communication between players via text chat (functional)}\\
Due to the lack of player vs player functionality this was never considered. However our application allows users to simultaneously participate in a game. As such it would be appropriate to include communication between players trying to work together to beat the computer; 
\item {\bf Profanity filter on text chat (non-functional)}\\
As previously stated above no chat feature was included, thus making this requirement obsolete
\end{itemize}

\end{itemize}

The following is a list of the known issues with regards to the functionality of the final application:

\begin{itemize}
\item {\bf Synchronisation Issues} \\
There can be an issue with the synchronisation in the program. This arises if a user makes their first click on a square that cannot possibly constitute a legal move. For example if the user were to click an empty square or a square containing an enemy piece. If this happens and the user then clicks on the piece they want to move the engine will treat this as an illegal move. There is no indication in the browser that this has happened and as such the user would need to resynchronize with the engine. This is done by making another false click before attempting to make another move. This could improved up on adding a highlight to the square that has been clicked an not allowing illegal squares to be clicked (see Section \ref{futurework}).



\end{itemize}

\section{Reflective Summary}
{\bf For the Implementation Report Only:}
\begin{itemize}
\item	What have you learnt through the process of development? 
\item	How did the application of frameworks help or hinder your progress? 
\item	What problems did you encounter? 
\item	What were your major achievements?
\end{itemize}

\section{Summary and Future Work}
\label{futurework}
\begin{itemize}
\item The client-side uses Javascript to able it to render a webpage, and uses simple HTML and HTTP to communicate with the rest of the system;
\item The middle-ware is written in C, and uses the Berkeley Sockets API, and standard library string.h;
\item The back-end is written in Java, and communicates with the middle-ware using Java sockets;
\item The chess engine already exists, from the Team Project 3 course, and uses Java architecture;
\item The main problem with the architecture is the communication between Server and chess engine. The team know of no natural way for these components to communicate, so there will have to be a substantial amount of research;
\item Plans for future development
\begin{itemize}
\item {\bf Player versus player support}\\
The ability for two players on different machines to play a game against each other.
\item {\bf Save games}\\
The ability to save and reload a particular game state.
\item {\bf Game statistics}\\
Store data about games, tell players what their win rate is, who they have played against and other important information.
\item Matchmaking\\
The ability to join a stranger in another game, based on skill level.
\item Logins\\
Mainly to integrate with other features, but players will be able to login and see their statistics, saved games etc.
\end{itemize}
\end{itemize}

\section{Acknowledgements}
Our thanks to the lecturers and demonstrators for their comments and suggestions. 

\newpage 
\pagebreak 
\newpage 
\pagebreak 
\newpage
\appendix{Appendix}
\newline
\begin{center}
\textbf{Figure 3. Sequence diagram for on-line chess}
\includegraphics[scale=0.6]{sequenceDiagram.png}
\end{center}
\newpage 
\pagebreak 
\begin{center}
\newpage 
\textbf{Figure 4. State diagram for on-line chess}
\includegraphics[scale=0.7]{diagram2.png}
\end{center}
\end{document}
